<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Packet timestamping</title>
<meta name="author" content="Miklos Maroti, Janos Sallai" />
<style type="text/css">

/*
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:date: $Date: 2009-02-03 23:07:32 $
:version: $Revision: 1.2 $
:copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.
*/
body {
  font-family: Times;
  font-size: 16px;
}

.first {
  margin-top: 0 ! important }

.last {
  margin-bottom: 0 ! important }

.hidden {
  display: none }

a.toc-backref {
  text-decoration: none ;
  color: black }

blockquote.epigraph {
  margin: 2em 5em ; }

dd {
  margin-bottom: 0.5em }

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.attention, div.caution, div.danger, div.error, div.hint,
div.important, div.note, div.tip, div.warning, div.admonition {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

div.hint p.admonition-title, div.important p.admonition-title,
div.note p.admonition-title, div.tip p.admonition-title,
div.admonition p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.dedication {
  margin: 2em 5em ;
  text-align: center ;
  font-style: italic }

div.dedication p.topic-title {
  font-weight: bold ;
  font-style: normal }

div.figure {
  margin-left: 2em }

div.footer, div.header {
  font-size: smaller }

div.line-block {
  display: block ;
  margin-top: 1em ;
  margin-bottom: 1em }

div.line-block div.line-block {
  margin-top: 0 ;
  margin-bottom: 0 ;
  margin-left: 1.5em }

div.sidebar {
  margin-left: 1em ;
  border: medium outset ;
  padding: 0em 1em ;
  background-color: #ffffee ;
  width: 40% ;
  float: right ;
  clear: right }

div.sidebar p.rubric {
  font-family: sans-serif ;
  font-size: medium }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1 {
  font-family: Arial, sans-serif;
  font-size: 20px;
}

h1.title {
 text-align: center;
 font-size: 32px;
}

h2 {
 font-size: 16px;
 font-family: Arial, sans-serif;
}

h2.subtitle {
  text-align: center }

h3 {
 font-size: 12px;
 font-family: Arial, sans-serif;
}

hr {
  width: 75% }

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.attribution {
  text-align: right ;
  margin-left: 50% }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.rubric {
  font-weight: bold ;
  font-size: larger ;
  color: maroon ;
  text-align: center }

p.sidebar-title {
  font-family: sans-serif ;
  font-weight: bold ;
  font-size: larger }

p.sidebar-subtitle {
  font-family: sans-serif ;
  font-weight: bold }

p.topic-title {
  font-weight: bold }

pre.address {
  margin-bottom: 0 ;
  margin-top: 0 ;
  font-family: serif ;
  font-size: 100% }

pre.line-block {
  font-family: serif ;
  font-size: 100% }

pre.literal-block, pre.doctest-block {
  margin-left: 2em ;
  margin-right: 2em ;
  background-color: #eeeeee;
  border-color: #000000;
  border-width: thin; 
  font-size: 14px
}

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option {
  white-space: nowrap }

span.option-argument {
  font-style: italic }

span.pre {
  white-space: pre }

span.problematic {
  color: red }

table {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

table.citation {
  border-left: solid thin gray ;
  padding-left: 0.5ex }

table.docinfo {
  margin: 2em 4em;
}

table.footnote {
  border-left: solid thin black ;
  padding-left: 0.5ex }

td, th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

th.docinfo-name, th.field-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap;
  }

h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
  font-size: 100% }

tt {}

ul.auto-toc {
  list-style-type: none }

</style>
</head>
<body>
<div class="document" id="packet-timestamping">
<h1 class="title">Packet timestamping</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr class="field"><th class="docinfo-name">TEP:</th><td class="field-body">TBA</td>
</tr>
<tr class="field"><th class="docinfo-name">Group:</th><td class="field-body">Core Working Group</td>
</tr>
<tr class="field"><th class="docinfo-name">Type:</th><td class="field-body">Documentary</td>
</tr>
<tr><th class="docinfo-name">Status:</th>
<td>Draft</td></tr>
<tr class="field"><th class="docinfo-name">TinyOS-Version:</th><td class="field-body">&gt; 2.1</td>
</tr>
<tr><th class="docinfo-name">Author:</th>
<td>Miklos Maroti, Janos Sallai</td></tr>
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">15-May-2008</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.1</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2008-06-17</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List &lt;tinyos-devel at mail.millennium.berkeley.edu&gt;</td>
</tr>
</tbody>
</table>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">This memo documents a part of TinyOS for the TinyOS Community, and requests
discussion and suggestions for improvements.  Distribution of this memo is
unlimited. This memo is in full compliance with TEP 1.</p>
</div>
<div class="section">
<h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>This TEP describes a mechanism that provides access to the time of transmission
and time of reception of a packet. The local clocks of the sender and recipient
are used to timestamp the transmission and reception of the packet,
respectively.</p>
</div>
<div class="section">
<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>Time of packet sending and reception is often of interest in sensor network
applications. Typically, neither the time of invocation of the send command, nor
the time of signaling of the sendDone event can be used to estimate, without
significant jitter, the time when the packet was transmitted. Similarly, the
time of occurrence of the receive event cannot be used to reliably estimate the
time of reception.</p>
<p>A straightforward way of message timestamping is to use the start-of-frame
delimiter interrupt, commonly exposed by packet-oriented radio transceivers.
This approach was taken by the CC2420 radio stack in TinyOS 1.x: the SFD
interrupt handler was exposed by the radio stack as an asynchronous event. This
solution was problematic, because higher- level application components that
wired the interface containing this event could break the timing of radio stack
due to excessive computation in interrupt context.</p>
<p>This TEP overcomes this issue by providing a standardized, platform- independent
interface to access packet timestamps without exposing timing critical and/or
hardware-specific events. Also, this TEP does not prescribe how packet
timestamping should be implemented: it only describes the interfaces and the
required functionality (semantics).</p>
</div>
<div class="section">
<h1><a id="the-packettimestamp-interface" name="the-packettimestamp-interface">2. The <tt class="docutils literal"><span class="pre">PacketTimeStamp</span></tt> interface</a></h1>
<p>This TEP specifies a standard interface (<tt class="docutils literal"><span class="pre">PacketTimeStamp</span></tt>) to access the
packet transmission and packet reception times. The sender and the receiver use
unsynchronized clocks to timestamp packets. The precision and width of
timestamps is specified as interface parameters <tt class="docutils literal"><span class="pre">precision_tag</span></tt> and
<tt class="docutils literal"><span class="pre">size_type</span></tt>:</p>
<pre class="literal-block">
interface PacketTimeStamp&lt;precision_tag, size_type&gt;
{
        async command bool isValid(message_t* msg);
        async command size_type timestamp(message_t* msg);
        async command void clear(message_t* msg);
        async command void set(message_t* msg, size_type value);
}
</pre>
<p>The <tt class="docutils literal"><span class="pre">timestamp</span></tt> command of the <tt class="docutils literal"><span class="pre">PacketTimeStamp</span></tt> interface is an accessor to the
the timestamp. The <tt class="docutils literal"><span class="pre">timestamp</span></tt> command returns the time
of transmission after a sendDone event, and the time of reception after a
receive event.</p>
<p>In some cases, it is not possible to timestamp certain packets (e.g. under very
heavy traffic multiple interrupts can occur before they could be serviced, and
even if capture registers are used, it is not possible to get the time stamp for
the first or last unserviced event). The <tt class="docutils literal"><span class="pre">PacketTimeStamp</span></tt> interface contains
the <tt class="docutils literal"><span class="pre">isValid</span></tt> command to query if the packet timestamp is valid.</p>
<p>The communications stack MUST guarantee that if the <tt class="docutils literal"><span class="pre">isValid</span></tt> command called
from within the <tt class="docutils literal"><span class="pre">sendDone</span></tt> or <tt class="docutils literal"><span class="pre">receive</span></tt> event handler returns <tt class="docutils literal"><span class="pre">TRUE</span></tt>, then
the value returned by the <tt class="docutils literal"><span class="pre">timestamp</span></tt> command can be trusted. However, it
might be possible that the local clock overflowed more than once or that is was
stopped or reset since the packet was timestamped, which causes the value
returned by the <tt class="docutils literal"><span class="pre">timestamp</span></tt> command invalid. The <tt class="docutils literal"><span class="pre">isValid</span></tt> command MAY
return TRUE in such situations, and it is the responsibility of the user of the
interface to ensure that the clock runs freely from the time of message
reception to the time when <tt class="docutils literal"><span class="pre">timestamp</span></tt> is called. To avoid this issue, it is
recommended that <tt class="docutils literal"><span class="pre">isValid</span></tt> and <tt class="docutils literal"><span class="pre">timestamp</span></tt> are called from the <tt class="docutils literal"><span class="pre">receive</span></tt>
or <tt class="docutils literal"><span class="pre">sendDone</span></tt> event handler.</p>
<p>The clear command invalidates the timestamp: after clear is called, <tt class="docutils literal"><span class="pre">isValid</span></tt>
will return <tt class="docutils literal"><span class="pre">FALSE</span></tt>. A <tt class="docutils literal"><span class="pre">set</span></tt> command is also included to allow for changing
the timestamp associated with the message. After the <tt class="docutils literal"><span class="pre">set</span></tt> command is called,
<tt class="docutils literal"><span class="pre">isValid</span></tt> will return TRUE.</p>
<p>The communications stack guarantees that the transmission timestamp and the
reception timestamp that belong to the same packet transmission always
correspond to the same physical phenomenon, i.e. to the same instance of
physical time. This TEP does not prescribe what synchronization event the
communications stack should use. For example, the communications stack may chose
to timestamps hardware events that correspond to the start of
transmission/reception of the packet, signaled a start-of-frame delimiter (SFD)
interrupt. The SFD interrupt occurs at the same time on the transmitter and the
receiver (assuming that the signal propagation delay is negligible).
Alternatively, on a byte oriented radio, the timestamp may correspond to the
average of the transmission times of bytes, as described in <a class="footnote-reference" href="#id5" id="id1" name="id1">[2]</a>.</p>
</div>
<div class="section">
<h1><a id="hil-requirements" name="hil-requirements">3. HIL requirements</a></h1>
<p>The signature of the platform's ActiveMessageC <a class="footnote-reference" href="#id6" id="id2" name="id2">[3]</a> MUST include:</p>
<pre class="literal-block">
provides interface PacketTimeStamp&lt;TMilli,uint32_t&gt;;
</pre>
<p>where timestamps are given in the node's local time, which is available through
<tt class="docutils literal"><span class="pre">HILTimerMilliC.LocalTime</span></tt> <a class="footnote-reference" href="#id7" id="id3" name="id3">[4]</a>.</p>
<p>The communications stack MAY support timestamp precisions and widths other than
<tt class="docutils literal"><span class="pre">TMilli</span></tt> and <tt class="docutils literal"><span class="pre">uint32_t</span></tt>, respectively. Also, alternative
<tt class="docutils literal"><span class="pre">TimesyncedPacket</span></tt> implementations MAY use clock sources other than
<tt class="docutils literal"><span class="pre">HILTimerMilliC.LocalTime</span></tt>.</p>
</div>
<div class="section">
<h1><a id="implementation" name="implementation">4. Implementation</a></h1>
<p>A reference implementation of the packet timestamping mechanism described in
this TEP can be found in <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/rf230</span></tt>.</p>
</div>
<div class="section">
<h1><a id="author-s-address" name="author-s-address">5. Author's Address</a></h1>
<div class="line-block">
<div class="line">Miklos Maroti</div>
<div class="line">Janos Sallai</div>
<div class="line">Institute for Software Integrated Systems</div>
<div class="line">Vanderbilt University</div>
<div class="line">2015 Terrace Place</div>
<div class="line">Nashville, TN 37203</div>
<div class="line">phone: +1 (615) 343-7555</div>
</div>
</div>
<div class="section">
<h1><a id="citations" name="citations">6. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id4" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id4">[1]</a></td><td>TEP 111: message_t</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id5" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1" name="id5">[2]</a></td><td>Maroti, M., Kusy, B., Simon, G., and Ledeczi, A. 2004. The flooding time synchronization protocol. In Proceedings of the 2nd international Conference on Embedded Networked Sensor Systems (Baltimore, MD, USA, November 03 - 05, 2004). ACM SenSys '04.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id6" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id2" name="id6">[3]</a></td><td>TEP 116: Packet protocols</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id7" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id3" name="id7">[4]</a></td><td>TEP 102: Timers</td></tr>
</tbody>
</table>
</div>
</div>
</body>
</html>
